/*
 * Copyright 2009 Armando Blancas
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package taskgraph.ports;

import java.io.IOException;
import java.util.IllegalFormatException;
import java.util.Locale;

/**
 * An output interface to a Char Channel.
 * 
 * @author Armando Blancas
 */
public interface CharOutputPort extends Port {
	
    /**
     * Writes a character to this output pipe.
     * 
     * @param c The {@code char} value to be written.
     * @return  This output port.
     * @throws IOException  If an I/O error occurs.
     */
	CharOutputPort write(char c) throws IOException;

    /**
     * Writes to the channel all the characters in array {@code c}.
     * If {@code c} is {@code null}, a {@code NullPointerException} is thrown. 
     * If {@code c.length} is zero, then no characters are written. Otherwise, 
     * the character {@code c[0]} is written first, then {@code c[1]}, and 
     * so on; the last character written is {@code c[c.length-1]}.
     *
     * @param c The {@code char} array to write.
     * @return  This output port.
     * @throws IOException If an I/O error occurs.
     */
	CharOutputPort write(char[] c) throws IOException;

    /**
     * Writes <code>len</code> characters from array <code>c</code>, in order, 
     * to the channel. If <code>c</code> is <code>null</code>, a <code>
     * NullPointerException</code> is thrown.  If <code>off</code> is negative,
     * or <code>len</code> is negative, or <code>off+len</code> is greater than
     * the length of the array <code>c</code>, then an <code>
     * IndexOutOfBoundsException</code> is thrown.  If <code>len</code> is zero,
     * then no characters are written. Otherwise, the character 
     * <code>c[off]</code> is written first, then <code>c[off+1]</code>, and so
     * on; the last character  written is <code>c[off+len-1]</code>.
     *
     * @param c The {@code char} array with the data to write.
     * @param off The start offset in the array.
     * @param len The number of characters to write.
     * @return  This output port.
     * @throws IOException If an I/O error occurs.
     */
	CharOutputPort write(char[] c, int off, int len) throws IOException;

    /**
     * Prints a string.  If the argument is <code>null</code> then the string
     * <code>"null"</code> is printed.  Otherwise, the string's characters are
     * converted into bytes according to the platform's default character
     * encoding, and these bytes are written in exactly the manner of the
     * <code>{@link #write(char c)}</code> method.
     *
     * @param s The <code>String</code> to be printed
     * @return  This output port.
     * @throws IOException If an I/O error occurs.
     */
	CharOutputPort print(String s) throws IOException;

    /**
     * Terminates the current line by writing the line separator string.  The
     * line separator string is defined by the system property
     * <code>line.separator</code>, and is not necessarily a single newline
     * character (<code>'\n'</code>).
	 *
     * @return  This output port.
     * @throws IOException If an I/O error occurs.
     */
	CharOutputPort println() throws IOException;

    /**
     * Prints a String and then terminates the line.  This method behaves as
     * though it invokes <code>{@link #print(String)}</code> and then
     * <code>{@link #println()}</code>.
     *
     * @param s the <code>String</code> value to be printed
     * @return  This output port.
     * @throws IOException If an I/O error occurs.
     */
	CharOutputPort println(String s) throws IOException;
    
    /**
     * Writes a formatted string.
     * 
     * Writes a formatted string to this pipe using the specified format
     * string and arguments.  If automatic flushing is enabled, calls to this
     * method will flush the output buffer.
     *
     * <p> The locale always used is the one returned by {@link
     * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
     * previous invocations of other formatting methods on this object.
     *
     * @param  format
     *         A format string as described in {@link java.util.Formatter}.
     *
     * @param  args
     *         Arguments referenced by the format specifiers in the format
     *         string.  If there are more arguments than format specifiers, the
     *         extra arguments are ignored.  The number of arguments is
     *         variable and may be zero.  The maximum number of arguments is
     *         limited by the maximum dimension of a Java array as defined by
     *         the <a href="http://java.sun.com/docs/books/vmspec/">Java
     *         Virtual Machine Specification</a>.  The behavior on a
     *         <tt>null</tt> argument depends on the conversion.
     *
     * @throws  IllegalFormatException
     *          If a format string contains an illegal syntax, a format
     *          specifier that is incompatible with the given arguments,
     *          insufficient arguments given the format string, or other
     *          illegal conditions.  For specification of all possible
     *          formatting errors, see the Details section of the
     *          Formatter class specification.
     *
     * @throws  NullPointerException
     *          If the <tt>format</tt> is <tt>null</tt>
     *
     * @return  This output port
     */
    CharOutputPort printf(String format, Object... args) throws IOException;
    
    /**
     * Writes a formatted string for a specific locale.
     * 
     * Writes a formatted string to this pipe using the specified format
     * string and arguments.  If automatic flushing is enabled, calls to this
     * method will flush the output buffer.
     *
     * <p> The locale always used is the one returned by {@link
     * java.util.Locale#getDefault() Locale.getDefault()}, regardless of any
     * previous invocations of other formatting methods on this object.
     *
     * @param  l
     *         The {@linkplain java.util.Locale locale} to apply during
     *         formatting.  If <tt>l</tt> is <tt>null</tt> then no localization
     *         is applied.
     *         
     * @param  format
     *         A format string as described in {@link java.util.Formatter}.
     *
     * @param  args
     *         Arguments referenced by the format specifiers in the format
     *         string.  If there are more arguments than format specifiers, the
     *         extra arguments are ignored.  The number of arguments is
     *         variable and may be zero.  The maximum number of arguments is
     *         limited by the maximum dimension of a Java array as defined by
     *         the <a href="http://java.sun.com/docs/books/vmspec/">Java
     *         Virtual Machine Specification</a>.  The behavior on a
     *         <tt>null</tt> argument depends on the conversion.
     *
     * @throws  IllegalFormatException
     *          If a format string contains an illegal syntax, a format
     *          specifier that is incompatible with the given arguments,
     *          insufficient arguments given the format string, or other
     *          illegal conditions.  For specification of all possible
     *          formatting errors, see the Details section of the
     *          Formatter class specification.
     *
     * @throws  NullPointerException
     *          If the <tt>format</tt> is <tt>null</tt>
     *
     * @return  This output port
     */
    CharOutputPort printf(Locale l, String format, Object... args)
    throws IOException;

}
